Review requested:

• @nodejs/quic
• @nodejs/security-wg

Building Node.js

Depending on what platform or features you need, the build process may
differ. After you've built a binary, running the
test suite to confirm that the binary works as intended is a good next step.

If you can reproduce a test failure, search for it in the
Node.js issue tracker or
file a new issue.

Table of contents

• Supported platforms
  • Input
  • Strategy
  • Platform list
  • Supported toolchains
  • Official binary platforms and toolchains
    • OpenSSL asm support
  • Previous versions of this document
• Building Node.js on supported platforms
  • Prerequisites
  • Unix and macOS
    • Unix prerequisites
    • macOS prerequisites
    • Building Node.js
    • Installing Node.js
    • Running Tests
    • Running Coverage
    • Building the documentation
    • Building a debug build
    • Building an ASan build
    • Speeding up frequent rebuilds when developing
      • ccache
      • Loading JS files from disk instead of embedding
    • Troubleshooting Unix and macOS builds
  • Windows
    • Windows Prerequisites
      • Option 1: Manual install
      • Option 2: Automated install with WinGet
    • Building Node.js
      • Using ccache
  • Android
• Intl (ECMA-402) support
  • Build with full ICU support (all locales supported by ICU)
    • Unix/macOS
    • Windows
  • Trimmed: small-icu (English only) support
    • Unix/macOS
    • Windows
  • Building without Intl support
    • Unix/macOS
    • Windows
  • Use existing installed ICU (Unix/macOS only)
  • Build with a specific ICU
    • Unix/macOS
    • Windows
• Configuring OpenSSL config appname
• Building Node.js with FIPS-compliant OpenSSL
• Building Node.js with Temporal support
• Building Node.js with external core modules
  • Unix/macOS
  • Windows
• Note for downstream distributors of Node.js

Supported platforms

This list of supported platforms is current as of the branch/release to
which it belongs.

Input

Node.js relies on V8 and libuv. We adopt a subset of their supported platforms.

Strategy

There are three support tiers:

• Tier 1: These platforms represent the majority of Node.js users. The
  Node.js Build Working Group maintains infrastructure for full test coverage.
  Test failures on tier 1 platforms will block releases.
• Tier 2: These platforms represent smaller segments of the Node.js user
  base. The Node.js Build Working Group maintains infrastructure for full test
  coverage. Test failures on tier 2 platforms will block releases.
  Infrastructure issues may delay the release of binaries for these platforms.
• Experimental: May not compile or test suite may not pass. The core team
  does not create releases for these platforms. Test failures on experimental
  platforms do not block releases. Contributions to improve support for these
  platforms are welcome.

Platforms may move between tiers between major release lines. The table below
will reflect those changes.

Platform list

Node.js compilation/execution support depends on operating system, architecture,
and libc version. The table below lists the support tier for each supported
combination. A list of supported compile toolchains is
also supplied for tier 1 platforms.

For production applications, run Node.js on supported platforms only.

Node.js does not support a platform version if a vendor has expired support
for it. In other words, Node.js does not support running on End-of-Life (EoL)
platforms. This is true regardless of entries in the table below.

Supported toolchains

Depending on the host platform, the selection of toolchains may vary.

Official binary platforms and toolchains

Binaries at https://nodejs.org/download/release/ are produced on:

Starting with Node.js 25, official Linux binaries are linked with libatomic and these systems
must have the libatomic runtime installed and available at execution time to run the binaries.
The package name for the libatomic runtime is typically libatomic or libatomic1 depending
on your Linux distribution.

OpenSSL asm support

OpenSSL-1.1.1 requires the following assembler version for use of asm
support on x86_64 and ia32.

For use of AVX-512,

• gas (GNU assembler) version 2.26 or higher
• nasm version 2.11.8 or higher in Windows

AVX-512 is disabled for Skylake-X by OpenSSL-1.1.1.

For use of AVX2,

• gas (GNU assembler) version 2.23 or higher
• Xcode version 5.0 or higher
• llvm version 3.3 or higher
• nasm version 2.10 or higher in Windows

Please refer to https://docs.openssl.org/1.1.1/man3/OPENSSL_ia32cap/ for details.

If compiling without one of the above, use configure with the
--openssl-no-asm flag. Otherwise, configure will fail.

Previous versions of this document

Supported platforms and toolchains change with each major version of Node.js.
This document is only valid for the current major version of Node.js.
Consult previous versions of this document for older versions of Node.js:

• Node.js 24
• Node.js 22
• Node.js 20

Building Node.js on supported platforms

Prerequisites

• [A supported version of Python][Python versions] for building and testing.
• Memory: at least 8GB of RAM is typically required when compiling with 4 parallel jobs (e.g: make -j4)

Unix and macOS

Unix prerequisites

• gcc and g++ >= 13.2 or clang and clang++ >= 19.1
• GNU Make 3.81 or newer
• [A supported version of Python][Python versions]
  • For test coverage, your Python installation must include pip.

Installation via Linux package manager can be achieved with:

• Nix, NixOS: nix-shell
• Ubuntu, Debian: sudo apt-get install python3 g++-12 gcc-12 make python3-pip
• Fedora: sudo dnf install python3 gcc-c++ make python3-pip
• CentOS and RHEL: sudo yum install python3 gcc-c++ make python3-pip
• OpenSUSE: sudo zypper install python3 gcc-c++ make python3-pip
• Arch Linux, Manjaro: sudo pacman -S python gcc make python-pip

FreeBSD and OpenBSD users may also need to install libexecinfo.

macOS prerequisites

• Xcode Command Line Tools >= 16.4 for macOS
• [A supported version of Python][Python versions]
  • For test coverage, your Python installation must include pip.

macOS users can install the Xcode Command Line Tools by running
xcode-select --install. Alternatively, if you already have the full Xcode
installed, you can find them under the menu Xcode -> Open Developer Tool -> More Developer Tools.... This step will install clang, clang++, and
make.

Nix integration

If you are using Nix and direnv, you can use the following to get started:

echo 'use_nix --arg sharedLibDeps {} --argstr icu small' > .envrc
direnv allow .
make build-ci -j12

Most dependencies will likely be available in the official nixpkgs cache,
although for some dependencies we have to deviate for the upstream repository,
in which case those will be built locally, or you can use the Cachix repository
for the project: cachix use nodejs. See https://docs.cachix.org/ for more
information.

The use of make build-ci is to ensure you are using the CONFIG_FLAGS
environment variable. You can also specify it manually:

./configure $CONFIG_FLAGS
make -j12

Passing the --arg sharedLibDeps {} instructs direnv and Nix to generate an
environment that uses the vendored-in native dependencies. Using the vendored-in
dependencies result in a result closer to the official binaries, the tradeoff
being the build will take longer to complete as you'd have to build those
dependencies instead of using the cached ones from the Nix cache. You can omit
that flag to use all the shared dependencies, or specify only some dependencies:

cat -> .envrc <<'EOF'
use nix --arg sharedLibDeps '{
  inherit (import ./tools/nix/sharedLibDeps.nix {})
    openssl
    zlib
  ;
}'
EOF

Passing the --argstr icu small instructs direnv and Nix to pass --with-intl=small in
the CONFIG_FLAGS environment variable. If you omit this, the prebuilt ICU from Nix cache
will be used, which should speed up greatly compilation time.

The use of direnv is completely optional, you can also use nix-shell directly,
e.g. here's a command you can use to build a binary for benchmarking purposes:

# Passing `--arg loadJSBuiltinsDynamically false` to instruct the compiler to
# embed the JS core files so it is no longer affected by local changes
# (necessary for getting useful benchmark results).
# Passing `--arg devTools '[]' --arg benchmarkTools '[]'` since we don't need
# those to build node.
nix-shell \
  --arg loadJSBuiltinsDynamically false \
  --arg devTools '[]' --arg benchmarkTools '[]' \
  --run 'make build-ci -j12'

mv out/Release/node ./node_old

# ...
# Make your local changes, and re-build node

nix-shell \
  --arg loadJSBuiltinsDynamically false \
  --arg devTools '[]' --arg benchmarkTools '[]' \
  --run 'make build-ci -j12'

nix-shell --pure --run './node benchmark/compare.js --old ./node_old  --new ./node http | Rscript benchmark/compare.R'

There are additional attributes you can pass, see shell.nix file for more details.

Building Node.js

If the path to your build directory contains a space, the build will likely
fail.

To build Node.js:

./configure
make -j4

We can speed up the builds by using Ninja. For more
information, see
Building Node.js with Ninja.

The -j4 option will cause make to run 4 simultaneous compilation jobs which
may reduce build time. For more information, see the
GNU Make Documentation.

The above requires that python resolves to a supported version of
Python. See Prerequisites.

After building, setting up firewall rules can avoid
popups asking to accept incoming network connections when running tests.

Running the following script on macOS will add the firewall rules for the
executable node in the out directory and the symbolic node link in the
project's root directory.

sudo ./tools/macos-firewall.sh

Installing Node.js

To install this version of Node.js into a system directory:

[sudo] make install

Running tests

To verify the build:

make test-only

At this point, you are ready to make code changes and re-run the tests.

If you are running tests before submitting a pull request, use:

make -j4 test

make -j4 test does a full check on the codebase, including documentation tests.

To run the linter, use make lint/vcbuild lint. It will lint JavaScript, C++, and Markdown files.

To fix auto fixable JavaScript linting errors, use make lint-js-fix.

If you are updating tests and want to run tests in a single test file
(e.g. test/parallel/test-stream2-transform.js):

tools/test.py test/parallel/test-stream2-transform.js

You can execute the entire suite of tests for a given subsystem
by providing the name of a subsystem:

tools/test.py child-process

You can also execute the tests in a test suite directory
(such as test/message):

tools/test.py test/message

You can execute tests that match a specific naming pattern using the wildcard
*. For example, to run all tests under test/parallel with a name that starts
with test-stream-:

tools/test.py test/parallel/test-stream-*
tools/test.py parallel/test-stream-*  # The test/ prefix can be omitted
# In some shell environments, you may need to quote the pattern
tools/test.py "test/parallel/test-stream-*"

The wildcard * can be used in any part of the path. For example, to run all tests
with a name that starts with test-inspector-, regardless of the directory they are in:

# Matches test/sequential/test-inspector-*, test/pa

Thanks @martenrichter, super interesting! This is great and I'd definitely be keen to include WebTransport as soon as we can, though it'll probably have to wait until nghttp3 merge the draft this depends on, which in turn looks like it's currently waiting on the final RFC.

This approach in rough concept looks like it'll fit neatly with the HTTP/3 API changes & internals split I'm going to propose shortly (aiming for a PR on Monday I think) so there shouldn't be a big practical issue to implement WebTransport with that. In practice for this code specifically I should warn you there's going to be massive conflicts line-by-line since I'm moving lots of things around, but it's largely just relocation rather than more substantial changes.

The only relevant that might change in approach is the ticket data and application options part, since I'm adding a new API to better split transport params from app ticket data, and pull application options entirely out from QUIC into the specific application implementation. It'll make sense shortly I hope 😄 watch this space.

Thanks @martenrichter, super interesting! This is great and I'd definitely be keen to include WebTransport as soon as we can, though it'll probably have to wait until nghttp3 merge the draft this depends on, which in turn looks like it's currently waiting on the final RFC.

I also expected this. So I am prepared with branch to do the rebases from time to time.

This approach in rough concept looks like it'll fit neatly with the HTTP/3 API changes & internals split I'm going to propose shortly (aiming for a PR on Monday I think) so there shouldn't be a big practical issue to implement WebTransport with that. In practice for this code specifically I should warn you there's going to be massive conflicts line-by-line since I'm moving lots of things around, but it's largely just relocation rather than more substantial changes.

Ok, I will look into it and rebase after it is merged. Most of the wt stuff is in addition to the existing mechanism, so it should not be much work.

The only relevant that might change in approach is the ticket data and application options part, since I'm adding a new API to better split transport params from app ticket data, and pull application options entirely out from QUIC into the specific application implementation. It'll make sense shortly I hope 😄 watch this space.

I will see, but it looks quite orthogonal to the wt changes.

"Make all old test run" (client side) done.

Go to the newer tests and fix them (done!) (Except the flow control features not implemented in nghttp3).

• Implement server side
• Make all old test run (server side)

Both done. (No change no node.js required for these steps.)

Cool to see this making progress. How far off are we from putting one or two small tests to demo the whole setup into here? That'd make it easier to discuss the API and try it all our end-to-end. Looks like the only tests so far are for settings config.

I had a bit more of a look here after your comment in #64192, I was curious about the onsessionid events, and how that works.

I think similarly to the HTTP/3 split and the existing HTTP/2 API, it would be nice to aim for a protocol-specific API that hides those internals, to expose the low-level protocol primitives but not the protocol internal working. I.e. to use the API, imo you shouldn't need to think about control streams and session ids, you just get the WT session CONNECT headers, you can allow or reject, and then you get easy to use streams within.

Maybe we have a http3Session.onWebTransportSession callback which fires (headers, wtSession) with a WebTransportSession object, and each WT session has onStream event that emits a WebTransportStream in turn. WebTransportSession would manage the control stream & underlying HTTP/3 session interactions, and WebTransportStreams would just give you an API for raw data & stream-linked datagrams. For users who are interested in the raw workings underneath, they can always reach down into the underlying HTTP/3 or QUIC session directly.

Just food for thought, we don't need to define all this immediately anyway. We can focus on the internals in the short term and work out the user-facing surface later, I'm just starting to spitball about how it's all going to glue together.

Cool to see this making progress. How far off are we from putting one or two small tests to demo the whole setup into here?

In principle, we have this already in my external test setup. I can also run it node server and node client. (Though I do it step by step). Once I am ready with these test I will port them over.

That'd make it easier to discuss the API and try it all our end-to-end. Looks like the only tests so far are for settings config.

That is because I have postponed it until my test are running. I know this is not ideal for looking into the api. But you can look here:
https://github.com/fails-components/webtransport/tree/nodenativequic/main/lib/http3native

All these files are in principle the steps to interact with the api, which would also be visible in a test.
And the layer is relatively thin.

I had a bit more of a look here after your comment in #64192, I was curious about the onsessionid events, and how that works.

Here are all event handlers of a wt session stream:

https://github.com/fails-components/webtransport/blob/b303d4d59cd15beb20046501d55b6ad1c11d6b44/main/lib/http3native/session.js#L66

(And if you want, I can also write, how to setup the tests, while I have not ported them to node native).

I think similarly to the HTTP/3 split and the existing HTTP/2 API, it would be nice to aim for a protocol-specific API that hides those internals, to expose the low-level protocol primitives but not the protocol internal working. I.e. to use the API, imo you shouldn't need to think about control streams and session ids, you just get the WT session CONNECT headers, you can allow or reject, and then you get easy to use streams within.

That is in principle, what my webtransport package is currently doing. Though its architecture aims at the old quiche binary addon. My plan is to make this layer thinner and then eventually, if it fits, put the remaining parts to node.js. So that it comes close to your idea. Though there are only minimal changes required to hide the id.
But I want to do it step by step, as I think I will be faster this way.

Note, I have also parsers for the capsule protocol (alternative transport on http/3 and http/2) currently only in js (what I would be happy to port it to C/C++).
Also for a WebSocket based fallback protocol which supports backpressure also in a polyfill.
All this are things, where one can think about integrating or using it in node.js, with a similar interface.

Maybe we have a http3Session.onWebTransportSession callback which fires (headers, wtSession) with a WebTransportSession object, and each WT session has onStream event that emits a WebTransportStream in turn. WebTransportSession would manage the control stream & underlying HTTP/3 session interactions, and WebTransportStreams would just give you an API for raw data & stream-linked datagrams. For users who are interested in the raw workings underneath, they can always reach down into the underlying HTTP/3 or QUIC session directly.

Yes something like this. But it is less dramatic.

Just food for thought, we don't need to define all this immediately anyway. We can focus on the internals in the short term and work out the user-facing surface later, I'm just starting to spitball about how it's all going to glue together.

Yes, first the internal and then the glue on top. But your vision is not so different from mine.

• Go to the newer tests and fix them (server side)

Done. (So quic client to node.js native server).

Next stop: node.js native client to node.js native server (currently it crashes).
After that: chromium and firefox to native server
And then first tests.

node.js native client to node.js native server (done!). (Chased several bugs for at least three weekends...)
Next: chromium and firefox to native server
And then finally first wt tests.